Super Audio

home *** CD-ROM | disk | FTP | other *** search

/ Super Audio / Super Audio.iso / replay / _armovie / documents / join < prev next >

Wrap

Text File | 1997-11-10 | 21.0 KB | 407 lines

HOW TO RUN JOIN +++++++++++++++ Related Documents: ToRunDiff AE7doc Extract (Version 2.19, 29 Apr. 1994). Author: CRose Date: 16 May, 1994. Version: 3.07 File Name: join WHAT DOES JOIN DO? - takes the components of an ARMovie and joins them together ----------------- to produce ARMovie files with or without video images and with or without sound. It can also produce ARMovie files with multiple sound tracks if video images are required, and when building a movie it can compress sound at 16 bits per sample down to 4 bits per sample (format 2, adpcm). THE SOURCE DATA - you need a directory containing the following: --------------- * a file called "Header" (more info. further down). * a sprite. * Images: [optional - without this data the ARMovie file generated will be sound only and will contain only one sound track] an Images0 directory containing image files called 00, 01, 02, 03, and so on up to a maximum of 76. After this you need to create another Images directory called Images1 and then carry on with 00,01,02, etc. again. * Keys data: Same naming convention as above. i.e. e.g. Keys0.00, Keys0.01, etc. * Sound data: sound can be read from an already existing ARMovie file or by default from data format files. DATA FORMAT FILES: the following files must exist in the source directory: For 8 bits per sample (exponential) - (line 13 in the header file): Need at least one sound track (obviously). Sound /* 1st soundtrack */ Sound2 /* 2nd soundtrack */ Sound3 /* and so on ... */ Sound4 etc. For 16 bits per sample - (line 13 in header file): As above: Samples Samples2 Samples3 etc. For 4 bits per sample - (line 13 in header file): As above: Adpcm Adpcm2 etc. ARMOVIE FILE: join must be supplied with the full path name of this file on the command line. THE HEADER FILE: --------------- The Header file used by Join must comply with the following format (examples further below), and it must be kept in the same directory as the sprite, image, keys, and sound data (see section above - "The Source Data"). If more than one sound track is required then lines 10 to 13 will be slightly different. This is explained under the heading "Multiple Sound Tracks" further down. String ARMovie String Movie name String date and copyright details String author and other details String video compression format identifier [1][0 -> no video] Decimal number x size in pixels Decimal number y size in pixels Decimal number z pixel depth in bits [16 or 8] Decimal number number of frames per second to project at String sound compression format identifier [0 -> no sound] Decimal number sound replay rate in Hz (or fractions of) Decimal number number of sound channels recorded ("reversed" if l<->r) Decimal number sound precision ("linear" if linear, "unsigned" if unsigned) Decimal number number of frames in a chunk The number of frames per chunk (last line above) must match the video data. This information can be found be looking at the header section of the ARMovie from which the images were extracted. HEADER EXAMPLE (one sound track only): ARMovie The Concert (c) Notts University 1991 Created by Notts University, digitised by Acorn Computers 1 160 pixels 128 pixels 16 bits per pixel 25 frames per second 1 12000 Hz samples 1 channel 8 bits per sample (exponential) 50 frames per chunk Multiple Sound Tracks --------------------- The single video track can have an arbitrary number of sound tracks associated with it. Extra sound track data for each sound parameter follows the sound track marker "|" plus the sound track number. Different sound tracks can have completely different parameters - compression format, sample rate, number of channels, number of bits per sample. The first sound track is played by default and does not follow a |1 marker - thus the first additional sound track has parameters following a |2 marker. HEADER EXAMPLE (multiple sound tracks): ARMovie The Concert (c) Notts University 1991 Created by Notts University, digitised by Acorn Computers 1 160 pixels 128 pixels 16 bits per pixel 25 frames per second 1 |2 1 |3 1 12000 Hz samples |2 16000 |3 20000 1 channel |2 2 channels |3 2 channels 8 bits per sample (exponential) |2 16 bits per sample |3 4 bits (adpcm) 50 frames per chunk THE COMMAND LINE ---------------- Parameters for running join on the command line are shown below, followed by specific examples. -help : on-line help (limited in comparison with this text). -dest f : set destination file name (default 'JoinOp'). -index N : select different Header, Images, Keys combination. -nokeys : prevent the key frames being written to the new ARMovie generated by join. (You can see whether or not an ARMovie has keys by looking at the end of the header section in the ARMovie). -size N : set chunk alignment size to N. Default is 2047 bytes. (The smaller the value of N, the smaller the size of the output file generated by join). This is an optimization parameter, the value of which depends upon the media being used. -source : set name of source directory. -armovie n file/s : name of ARMovie sound source file/s. 'n' is the number of files specified, for example, -armovie 3 $.dir1.file1 $.dir1.file2 $.dir2.file3 (all on the same line). "file1" will provide the first sound track, "file2" will provide the second sound track, and "file3" will provide the third sound track. If e.g. file1 provided both sound tracks 1 and 2 and file2 provided the third sound track, then the -armovie parameter list would be -armovie 2 $.dir1.file1 $.dir1.file2 . n simply tells join how many ARMovie sound source files you are about to specify. It is nothing to do with the number of sound tracks. Examples are included below. EXAMPLES OF HOW TO RUN JOIN: --------------------------- Example 1: join -help --------- This will provide on-line help. It will also tell you the version number and date of the program. Obviously, this document provides more information than join -help does. Example 2: join -source $.DataToJoin --------- This will generate an ARMovie file using source data held in the directory $.DataToJoin (source data being the header, sprite, and so on as explained at the beginning of this document). By default, the name of the new ARMovie file will be "JoinOp". The information which you supply in the header determines whether or not the ARMovie file will have sound, whether or not it will have image data, what the sound replay rate will be, and so on (see Header sections above). If line ten of your header is 0 then join will not look for any sound data but if it is 1 then join will expect to see one or more sound files in $.DataToJoin or it will expect you to specify one or more ARMovie sound source files (examples 4,5, and 7 below). (If you want more than one sound track do not forget to indicate this in your header - see sub heading "Multiple Sound Tracks" above). Example 3: join -source $.DataToJoin -dest $.Movies.Elephants --------- This will generate an ARMovie file called "Elephants" in the directory called $.Movies, using source data held in the directory $.DataToJoin. Explanation is identical to example 2 above with the exception that the name of the generated ARMovie file no longer defaults to "JoinOp". Example 4: join -source $.DataToJoin -armovie 3 cdfs::replay_demo.$.movies. --------- shuttle $.DataToJoin.Planes $.Movies.Elephants (all on one line). This will generate an ARMovie file called "JoinOp" using the source data held in $.DataToJoin. The -armovie parameter instructs join to use sound from other ARMovie files rather than use sound from ordinary sound files. ARMovie file/s acting as the sound source do not necessarily have to live in the same directory as all the other source data, which is why you must specify full path names as shown in this example. So this example will generate an ARMovie file with three sound tracks. The first sound track will be extracted from cdfs:: replay_demo.$.movies.shuttle, the second sound track will be extracted from $.DataToJoin.Planes, and the third sound track will be extracted from $.Movies.Elephants. Your header file in $.DataTo Join must also indicate that there is to be three sound tracks (refer to the sub heading - "Multiple Sound Tracks" above). You should look at the header sections in your ARMovie sound source files to see what the sound replay rates are and what the sound precision should be for a particular sound track in your own header. The number 3 after -armovie simply tells join that there are three sound file parameters to read next. It does not tell join anything about the number of sound tracks. Example 7 is useful at this point. Example 5: join -source $.DataToJoin -armovie 2 cdfs::replay_demo.$.movies.horses --------- cdfs::replay_demo.$.movies.shuttle This example is identical to example 4 above with the exception that it will generate an ARMovie file called "JoinOp" with two sound tracks instead of three. Hence 2 follows -armovie instead of the previous number 3. You must also ensure that your header file in $.DataToJoin complies with what you have specified on the command line ie. in this example you are telling join to look for two sound tracks so lines ten to thirteen of your header must indicate this (refer to the sub heading - "Multiple Sound Tracks" above). You should look at the header sections in your ARMovie sound source files to see what the sound replay rates are and what the sound precision should be for a particular sound track in your own header). Example 6: join -source $.JoinData -index 3 -dest $.Movies.horses --------- This will generate an ARMovie file called $.Movies.horses using source data found in the directory $.JoinData but the -index parameter tells join to select a different set of images and keys and a different header. In this case, join will look for the directories $.JoinData.3Images0 and $.JoinData.3Keys0, and it will read from the header called $.JoinData.3Header . Example 7: join -source $.JoinData -armovie 2 $.oldmovie $.Movies.horses --------- You could do this if your header indicated that two sound tracks were required and one sound track was in $.oldmovie, the other in $.Movies.horses . You would also use this join command if your header indicated that three sound tracks were required, two of the sound tracks being in $.oldmovie and the third one being in $.Movies.horses (or one track being in oldmovie, the other two being in horses). The number 2 tells join how many ARMovie sound source files it must use. It does not tell join anything about the number of sound tracks. Similarly, if your header indicated that five sound tracks were required and $.oldmovie had five sound tracks, you would say join -source $.JoinData -armovie 1 $.oldmovie . COMPRESSION DOWN TO 4 BITS PER SAMPLE: ------------------------------------- Join will allow you to compress 16 bits per sample sound down to 4 bits per sample (adpcm) format 2 when building an ARMovie. To do this via the front end (!AREncode) you need to click on the compress box when building the ARMovie. To do this without using !AREncode you join the movie components in the normal way but you make sure that the sound format in your header reads "2 adpcm" and that your header reads 16 bits per sample. Join will then know to compress it down. Compression does not apply when building multiple track ARMovies. OTHER POINTS WORTH MENTIONING / TROUBLESHOOTING: ----------------------------------------------- Join will not read image data from anywhere but the image files in the source directory. It cannot read image data from another ARMovie file. If you do want to use image files from another ARMovie file this can be done via use of the Extract program mentioned at the end of this document. If there are no image files, only one sound track will be generated so the header information should only ask for 1 sound track and line 5 of the header should be zero. If ARMovie files are the sound source, lines 11 to 13 inclusive in header sections of these source files should correspond to the relevent track numbers in your own header (see sub-heading "Multiple Sound Tracks" above). If you use the -armovie parameter and the ARMovie file generated by join is obviously garbage, play back the original ARMovie source file/s and check that none of these are corrupt (e.g. if join was stopped by the user before completion then the generated ARMovie file will be corrupt and will therefore give problems if it is later used by join again as a source for the sound data in generating another ARMovie file). If you play back the newly generated ARMovie file and it freezes unexpectedly, make sure that you haven't attempted to run the movie with an invalid sound track number. e.g. if you played the ARMovie by typing $.JoinOp -tracks 3 on the command line and JoinOp did not have a third sound track this would cause the movie to freeze at the start. If your new ARMovie runs out of sound on a particular sound track and you think it shouldn't have, check that the replay rate (line 11) in your header is identical to the replay rate given in the ARMovie sound source file for that particular track (this of course does not apply if you are not using the -armovie parameter with join). e.g. if you use an ARMovie file with a sound track created at 12000 Hz and in your own header you indicate that this track is now to be created at 13000 Hz, you will obviously run out of sound data if the files were previously identical in size. This does not matter as join will adjust the catalogue information resulting in a period of silence at the end. You cannot output to the same ARMovie file that you are reading sound data from (this applies to use of the -armovie parameter). e.g. join -source $.DataToJoin -dest $.runfile -armovie $.runfile is illegal. Join will tell you that it is unable to open $.runfile. If -armovie is given on the command line, join will not look for local Sound, Samples, or Adpcm files. If you want to generate an Armovie using sound from an already existing Armovie AND from a Sound, Samples, or Adpcm file, you should first convert the Sound, Samples, or Adpcm file into an Armovie (using join) and then simply join the two together. If the files given after -armovie have multiple sound tracks, join will try to use all the tracks in accordance with your header (see example 7 above). For example, if your header indicates that the new Armovie will have six sound tracks, you could use three Armovie files as the sound source. The first Armovie might have three sound tracks, the second might have two, and the third would have only one, adding up to give a total of six tracks as specified in your header. The total number of sound tracks in the source files must add up to the number of sound tracks you specify in your header. Alternatively, for a six track header, you could use one Armovie with five sound tracks and another Armovie with only one sound track, or you could use two Armovies each with three sound tracks, and so on. If join is terminated prematurely (e.g. user presses escape), an exception handler will ensure that any open files are closed. For obvious reasons this only applies to files opened by join. There are two classes of error message. Warning errors may be ignored depending on context and whether or not a fatal error follows. Fatal errors will actually stop the program at that point. As mentioned above, any files left open by join will be closed by the exception handler. As well as taking in parameters from the command line, join will also look for parameters held in the environment variable join$ExtraArgs. The split can occur anywhere. e.g. join -source $.DataToJoin -de may be entered on the command line, while st $.runit may be held in join$ExtraArgs. join will simply join the two together to produce join -source $.DataTojoin -dest $.runit. A separate program exists called "extract", which does the reverse of what "Join" does. "Extract" can take an ARMovie file and extract its header, sprite, keys (if there are any), sound track/s, and images. It is perfectly acceptable for this extracted data to be used by Join. (Extract is accompanied by written documentation which you should read if you have never used it before). If you want join to use sound tracks from other ARMovie files join can do this directly (as mentioned many times above) using the -armovie parameter. But if you want join to use image data from other ARMovie files you must use Extract to generate the image data which can then be used by join. DIFFERENCES BETWEEN CURRENT VERSION (3.07) & PREVIOUS VERSION (3.06): ---------------------------------------------------------------------------- In the previous version it was a requirement that the string "frames per second" be present along with the actual value in the header. This requirement no longer applies. OUTSTANDING: ----------- ===================================================================================